Email Functions

Use the Email adapter to send email to simulation admins and participants from your application code.

Importing the adapter

To use the functions of the Email adapter, import it as shown:

import { emailAdapter } from 'epicenter-libs';

The emailAdapter namespace exports functions that make calls to the Email API.

learn more

For descriptions of the objects used by the Email adapter functions, read Email entities.

---

Email a participant

Use this function to allow a simulation participant or facilitator to send an email to another user within a group.

note

There are two options for the sender/reply-to address:

1. The sender is identified as "System". This method is available to participants.
2. The sender is identified as a specific user. Requires REVIEWER-level authentication. To use this method, pass the following parameters:
   • optionals.from: The email address from which the message will appear to have been sent from.
   • optionals.replyTo: The email address that will be replied to by the recipient.
   • optionals.fromUserKey: The user key of the sender user. Overrides optionals.from.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The sendEmail() function:

• Constructs a POST request to the endpoint /email/user/{groupKey}/{userKey}.
• Supports various options to customize the sender, reply-to address, email body format, and attachments.
• Returns void to indicate a successful request.

Function signature

export async function sendEmail(
    groupKey: string,
    userKey: string,
    subject: string,
    emailBody: string,
    optionals: {
        familyNameFirst?: string,
        html?: boolean,
        body?: string,
        from?: string,
        replyTo?: string,
        fromUserKey?: string,
        attachments?: {
            encoding: keyof typeof ENCODING,
            data: string,
            name: string,
            contentType: string,
        }[]
    } & RoutingOptions = {}
): Promise<void>

Parameters

• groupKey (string): The group key for the group the target user is a part of.
• userKey (string): The unique key identifying the recipient user.
• subject (string): The subject line.
• emailBody (string): The content of the email body.
• optionals (object, optional): Additional email and routing options:
  • familyNameFirst (string, optional): If true, formats the recipient’s family name before the given name. Defaults to false.
  • html (boolean, optional): If true, treats the email body as HTML. Defaults to false.
  • body (string, optional): Alternate content body of the email.
  • from (string, optional): Provide a custom sender email address here. However, if fromUserKey is provided, this is ignored.
  • replyTo (string, optional): Reply-to address. Can only be used in tandem with from.
  • fromUserKey (string, optional): Sends the email as if from the specified user.
  • attachments (Array<object>, optional): List of attachments to include:
    • encoding (string): The encoding type. See ENCODING values.
    • data (string): Base64 string containing the file data.
    • name (string): The attachment filename.
    • contentType (string): MIME type of the attachment.
  • Also accepts RoutingOptions.

Return value

A promise that resolves to void, indicating the email was sent successfully.

Usage example

import { emailAdapter } from 'epicenter-libs';

const groupKey = epicenter.authAdapter.getLocalSession().groupKey;
const subject = "check out this drawing!";
const body = "I hope you enjoy this smiley face!";

const attachments = [{
    encoding: 'BASE_64',
    name: 'testPic',
    contentType: 'image/png',
    data: 'iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAA...',
}];

// Send email with attachment, system as sender
await emailAdapter.sendEmail(groupKey, '000001796733eef0842f4d6d960997018a3b', subject, body, { attachments });

// Send email with custom "from" address
await emailAdapter.sendEmail(groupKey, '000001796733eef0842f4d6d960997018a3b', subject, body, {
    attachments,
    from: 'sender@test.com'
});

---

Email an admin

Use this function to allow an admin to send an email to another admin.

note

Requires support-level authentication.

Permissions

Requires a role of SUPPORT or higher.

Function description

The sendEmailToAdmin() function:

• Constructs a POST request to the endpoint /email/admin/{adminKey}.
• Supports customization of the email format, sender details, and attachments.
• Returns void to indicate a successful request.

Function signature

export async function sendEmailToAdmin(
    adminKey: string,
    subject: string,
    emailBody: string,
    optionals: {
        familyNameFirst?: string,
        html?: boolean,
        body?: string,
        attachments?: {
            encoding: keyof typeof ENCODING,
            data: string,
            name: string,
            contentType: string,
        }
    } & RoutingOptions = {}
): Promise<void>

Parameters

• adminKey (string): The unique key identifying the target admin.
• subject (string): The subject line.
• emailBody (string): The content of the email body.
• optionals (object, optional): Additional email and routing options:
  • familyNameFirst (string, optional): If true, formats the recipient’s family name before the given name. Defaults to false.
  • html (boolean, optional): If true, treats the email body as HTML. Defaults to false.
  • body (string, optional): Alternate content body of the email.
  • attachments (object, optional): A single attachment object with the following properties:
    • encoding (string): The encoding type. See ENCODING values.
    • data (string): Base64 string containing the file data.
    • name (string): The attachment filename.
    • contentType (string): MIME type of the attachment.
  • Also accepts RoutingOptions.

Return value

A promise that resolves to void, indicating the email was sent successfully.

Usage example

import { emailAdapter } from 'epicenter-libs';

const adminKey = '000001796733eef0842f4d6d960997018a3b';
const subject = "Important update";
const body = "Please review the attached document.";

const attachment = {
    encoding: 'BASE_64',
    name: 'update.pdf',
    contentType: 'application/pdf',
    data: 'JVBERi0xLjQKJcfs...'
};

// Send email with attachment
await emailAdapter.sendEmailToAdmin(adminKey, subject, body, {
    attachments: attachment
});

// Send email with HTML formatting
await emailAdapter.sendEmailToAdmin(adminKey, subject, body, {
    html: true,
    attachments: attachment
});

---

Email support

To allow a user to send an email directly to the Epicenter support team, use the sendEmailToSupport() function.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

• Constructs a POST request to the endpoint /email/to/support.
• Accepts optional parameters for support type, formatting, and attachments.
• Returns void upon successful submission.

Function signature

export async function sendEmailToSupport(
    subject: string,
    emailBody: string,
    optionals: {
        supportType?: string;
        familyNameFirst?: string;
        html?: boolean;
        attachments?: {
            encoding: keyof typeof ENCODING;
            data: string;
            name: string;
            contentType: string;
        }[];
    } & RoutingOptions = {},
): Promise<void>

Parameters

• subject (string): The subject line for the email message.
• emailBody (string): The email body.
• optionals (object, optional): Additional configuration and routing options.
  • supportType (string, optional): Indicates the type of the support request (for example, "technical" or "billing").
  • familyNameFirst (string, optional): If true, formats the recipient’s family name before the given name. Defaults to false.
  • html (boolean, optional): If true, treats the email body as HTML. Defaults to false.
  • attachments (Array<object>, optional): A list of attachments to include with the email.
    • encoding (string): The encoding method. See ENCODING values.
    • data (string): Encoded string representing the attachment data.
    • name (string): The filename of the attachment.
    • contentType (string): MIME type of the attachment.
  • Also accepts RoutingOptions to control network routing.

Return value

A promise that resolves to void, indicating the email was sent successfully.

Usage example

import { emailAdapter } from 'epicenter-libs';

const subject = "Simulation not loading correctly";
const body = "Hi Support, I'm having trouble loading my project. Can you help?";

const attachments = [{
    encoding: 'BASE_64',
    name: 'error-log.txt',
    contentType: 'text/plain',
    data: 'U29tZSBsb2cgZGF0YSBoZXJlLi4u', // base64-encoded data
}];

// Send a plain text support email
await emailAdapter.sendEmailToSupport(subject, body);

// Send an HTML email with attachment and custom support type
await emailAdapter.sendEmailToSupport(subject, body, {
    html: true,
    supportType: 'technical',
    attachments,
});

---